home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / options.lha / options / README < prev    next >
Text File  |  1993-04-13  |  5KB  |  158 lines
  1.  
  2.  WHAT IS THIS?
  3.  =============
  4.  This is "Options", a C++ library for parsing Unix-style command-line options.
  5.  Options understands options and gnu-long-options and the parsing behavior is
  6.  somewhat configurable. See the documentation (or the file <options.h>) for a
  7.  complete description.
  8.  
  9.  You "declare" your options by declaring an array of strings like so:
  10.  
  11.         const char * optv[] = {
  12.             "c:count <number>",
  13.             "s?str   <string>",
  14.             "x|xmode",
  15.             NULL
  16.         } ;
  17.   
  18.  Note the character (one of ':', '?', '|', '*', or '+') between the short
  19.  and long name of the option. It specifies the option type:
  20.  
  21.         '|' -- indicates that the option takes NO argument;
  22.         '?' -- indicates that the option takes an OPTIONAL argument;
  23.         ':' -- indicates that the option takes a REQUIRED argument;
  24.         '*' -- indicates that the option takes 0 or more arguments;
  25.         '+' -- indicates that the option takes 1 or more arguments;
  26.  
  27.  Using the above example, optv[] now corresponds to the following:
  28.  
  29.         progname [-c <number>] [-s [<string>]] [-x]
  30.  
  31.  Using long-options, optv corresponds to the following ("-" or "+" may
  32.  be used instead of "--" as the prefix):
  33.   
  34.         progname [--count <number>] [--str [<string>]] [--xmode]
  35.  
  36.  Now you can iterate over your options like so:
  37.  
  38.       #include <stdlib.h>
  39.       #include <options.h>
  40.  
  41.       main(int argc, char *argv[]) {
  42.          Options  opts(*argv, optv);
  43.          OptArgvIter  iter(--argc, ++argv);
  44.          const char *optarg, *str = NULL;
  45.          int  errors = 0, xflag = 0, count = 1;
  46.       
  47.          while( char optchar = opts(iter, optarg) ) {
  48.             switch (optchar) {
  49.             case 's' :
  50.                str = optarg; break;
  51.             case 'x' :
  52.                ++xflag; break;
  53.             case 'c' :
  54.                if (optarg == NULL)  ++errors;
  55.                else  count = (int) atol(optarg);
  56.                break;
  57.             default :  ++errors; break;
  58.             } //switch
  59.          }
  60.          ...  // process the rest of the arguments in "iter"
  61.       }
  62.  
  63.  
  64.  AUTHOR
  65.  ======
  66.  Brad Appleton                     Harris Corp., Computer Systems Division
  67.    Senior Software Engineer        2101 West Cypress Creek Road,  M/S 161 
  68.      brad@ssd.csd.harris.com       Fort Lauderdale, FL  33309-1892  USA
  69.        ...!uunet!travis!brad              Phone: (305) 973-5190
  70.  
  71.  
  72.  COPY/REUSE POLICY
  73.  =================
  74.  Permission is hereby granted to freely copy and redistribute this
  75.  software, provided that the author is clearly credited in all copies
  76.  and derivations. Neither the names of the authors nor that of their
  77.  employers may be used to endorse or promote products derived from this
  78.  software without specific written permission.
  79.  
  80.  
  81.  DISCLAIMER
  82.  ==========
  83.  This software is provided ``As Is'' and without any express or implied
  84.  warranties.  Neither the authors nor any of their employers (including
  85.  any of their subsidiaries and subdivisions) are responsible for maintaining
  86.  or supporting this software or for any consequences resulting from the
  87.  use of this software, no matter how awful, even if they arise from flaws
  88.  in the software.
  89.  
  90.  
  91.  CONTENTS
  92.  ========
  93.  See the file "MANIFEST" in the distribution for a complete list and
  94.  description of all the files included in this release.
  95.  
  96.  
  97.  REQUIREMENTS
  98.  ============
  99.  This software should compile on most Unix platforms with a C++ compiler
  100.  with little or no difficulty.
  101.  
  102.  
  103.  PORTING
  104.  =======
  105.  Options uses the AT&T C++ iostream library.  Beyond that, all the
  106.  #include files it uses are assumed to have the contents specified by
  107.  the ANSI-C standard and are assumed to have #ifdef __cplusplus statements
  108.  for when they are being included by C++ files.  Options assumes the
  109.  existence of the following system header files:
  110.  
  111.          <stdarg.h>
  112.          <stdlib.h>
  113.          <string.h>
  114.          <ctype.h>
  115.          <iostream.h>
  116.  
  117.   Other porting problems you may experience are as follows:
  118.  
  119.     - you may need to use <varargs.h> instead of <stdarg.h>
  120.  
  121.  You will need to tweak the Makefile a tad in order to make it work
  122.  for your C++ compiler.
  123.  
  124.  
  125.  BUGS
  126.  ====
  127.  Please send all bug reports to Brad Appleton <brad@ssd.csd.harris.com>.
  128.  Dont forget to mention which version of Options you have and which
  129.  operating system and C++ compiler you are using.
  130.  
  131.  
  132.  ACKNOWLEDGEMENTS
  133.  ================
  134.  Options is a complete C++ re-write of an ANSI-C package named "getopts"
  135.  that I wrote for the FSF that was posted on one of the "gnu" newsgroups
  136.  (I think it was the group gnu.utils.bug) in February of 1992.  Many thanks
  137.  to David J. MacKenzie for his input.  Options provides may more features
  138.  than "getopts" did.  If you want the original "getopts" package (which
  139.  has since been vastly enhanced) then send me e-mail.
  140.  
  141.  
  142.  PATCHLEVEL
  143.  ==========
  144.  The is release 1 of Options at patchlevel 1.
  145.  
  146.  
  147.  HISTORY
  148.  =======
  149.  
  150.  07/21/92        Brad Appleton        <brad@ssd.csd.harris.com>
  151.  -----------------------------------------------------------------------------
  152.  First release.
  153.  
  154.  03/23/93        Brad Appleton        <brad@ssd.csd.harris.com>
  155.  -----------------------------------------------------------------------------
  156.  - Made some changes for compiling with g++
  157.  - Added OptIstreamIter class
  158.